home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 April / macformat-023.iso / Shareware City / Developers / NeoPersist 3.0.8 folder / NeoIncludes / CNeoPersist.h < prev    next >
Encoding:
C/C++ Source or Header  |  1994-10-13  |  8.0 KB  |  186 lines  |  [TEXT/MMCC]
  1. /************************************************************
  2.  *
  3.  *    Created: Saturday, May 11, 1991 12:55:02 PM
  4.  *    CNeoPersist.h
  5.  *    Definitions for a persistent object class
  6.  *
  7.  *
  8.  *    Copyright © Neologic Systems 1992-1994. All Rights Reserved.
  9.  *    All rights reserved
  10.  *
  11.  *
  12.  * Object persistence and integrity is provided by the CNeoPersist class. Persistent
  13.  * objects are first class citizens. A newly created persistent object is created
  14.  * through the use of the new operator. The object can be made permanent by using
  15.  * the database's addObject method. This associates the object with a database and assigns it
  16.  * an identity. Identity is simply a value that, in conjunction with with the class
  17.  * of the object, can be used find the object in the database. In order to unambiguously
  18.  * refer to it, an object should have a unique identity within its class within its
  19.  * database. In some situations ambiguity may be desirable, so finding all objects of a
  20.  * given base class having a given identity is supported.
  21.  *
  22.  * Typically, permanent objects are sorted within their class in ascending ID
  23.  * order. This allows the use of binary searches to locate objects given a ID
  24.  * value. However custom indexing strategies are also supported.
  25.  *
  26.  * The method remove() breaks the association between object and database.
  27.  *
  28.  * The unrefer() method of persistent objects supports the object's
  29.  * reference count mechanism. This method decrements the reference count. If the count
  30.  * goes to zero and the object is not locked, then the object is purgeable. Purgeable
  31.  * objects can be freed during purging. Purging, which is usually invoked from the
  32.  * application's GrowZone routine, involves traversing the class and free lists
  33.  * freeing purgeable objects until a large enough node of memory is found.
  34.  *
  35.  * The impact of this referential integrity and transparent persistence mechanism
  36.  * should be considered from a number of different perspectives. From a memory
  37.  * standpoint, the CNeoPersist class adds 16 bytes to the size of every persistent
  38.  * object. The overhead of maintaining the indexes and class lists in memory typically
  39.  * adds an additional 12 bytes per permanent object. However, these numbers are offset
  40.  * by several factors. From a memory usage standpoint, this mechanism is very
  41.  * agressive about minimizing its memory footprint by purging when memory is needed.
  42.  * From a performance perspective, the system is optimally fast at locating objects.
  43.  * And finally from the point of view of the developer, the visible complexity of the
  44.  * system is greatly reduced by integrating object persistence into the framework.
  45.  *
  46.  ***********************************************************/
  47. #pragma once            /* Include this file only once */
  48. #ifndef __CNeoPersist__
  49. #define __CNeoPersist__ 1
  50.  
  51. #include "NeoTypes.h"
  52. #include <AERegistry.h>
  53.  
  54. #ifdef CNeoPersistBaseH
  55. #include CNeoPersistBaseH
  56. #endif
  57.  
  58. class CNeoMetaClass;
  59. class CNeoDatabase;
  60. class CNeoContainerStream;
  61.  
  62. class CNeoPersist
  63. {
  64. public:
  65.                         /** Instance Methods **/
  66.     void *                operator new(size_t aSize);
  67.     void                operator delete(void *aObject, size_t aSize);
  68.     static void *        CacheMalloc(size_t aSize);
  69.                         CNeoPersist(void);
  70.     virtual                ~CNeoPersist(void);        // Just so that destructors are all virtual
  71.     static CNeoPersist *New(void);
  72.     virtual NeoID        getClassID(void) const;
  73.     void                getClassName(CNeoString &aName) const;
  74.     virtual long        getFileLength(void) const;
  75.     CNeoMetaClass *        getMetaClass(void) const;
  76.     virtual CNeoSelect *getUniqueKey(void);
  77.     virtual OSErr        getValue(const NeoTag aName, const NeoTag aType, void *aValue);
  78.     virtual OSErr        setValue(const NeoTag aName, const NeoTag aType, const void *aValue);
  79.     static OSErr        ConvertType(const void *aSource, const NeoTag aSourceType, void *aDest, const NeoTag aDestType);
  80.  
  81.                         /** I/O Methods **/
  82.     virtual void        readObject(CNeoStream *aStream, const NeoTag aTag);
  83.     virtual void        writeObject(CNeoStream *aStream, const NeoTag aTag);
  84.     virtual Boolean        commit(CNeoContainerStream *aStream, const Boolean aCompletely, const Boolean aCompress, const Boolean aDeeply);
  85.  
  86.                         /** Searching Methods **/
  87.     static void *        FindByID(CNeoDatabase *aDatabase, const NeoID aClassID, const NeoID aID, const Boolean aDeeply, NeoTestFunc1 aFunc = nil, void *aParam = nil, const NeoLockType aLock = kNeoDefaultLock);
  88.     static void *        FindEvery(CNeoDatabase *aDatabase, const NeoID aClassID, const Boolean aDeeply, NeoTestFunc1 aFunc = nil, void *aParam = nil, const NeoLockType aLock = kNeoDefaultLock);
  89.  
  90.                         /** Tree Management Methods **/
  91.     virtual void        forgetChild(CNeoPersist *aChild);
  92.     virtual void        forgetChildren(const short aIndex);
  93.     CNeoPersist *        getParent(void) const {return fParent;}
  94.     static Boolean        IsLeaf(const NeoMark aMark);
  95.     void                setParent(CNeoPersist *aParent) {fParent = aParent;}
  96.     virtual void        setSubtree(CNeoNode *aOldRoot, CNeoNode *aNewRoot);
  97.  
  98.                         /** Persistence Methods **/
  99.     virtual void        add(void);
  100.     NeoMark                getMark(void) const {return fMark;}
  101.     NeoID                getID(void) const {return fID;}
  102.     NeoVersion            getVersion(void) const {return fVersion;}
  103.     Boolean                isDirty(void) const {return (Boolean)(fDirty != kNeoClean);}
  104.     Boolean                isTemporary(void) const {return fTemporary;}
  105.     virtual void        remove(void);
  106.     virtual void        relocate(const NeoMark aNewMark);
  107.     void                setDirty(const NeoDirty aReason = kNeoChanged);
  108.     virtual void        setID(const NeoID aID);
  109.     virtual void        update(CNeoPersist *aObject);
  110.  
  111.                         /** Concurrency Methods **/
  112.     NeoRefCnt            getRefCnt(void) const {return fRefCnt;}
  113.     void                referTo(void);
  114.     NeoRefCnt            unrefer(void);
  115.     void                autoReferTo(void);
  116.     NeoRefCnt            autoUnrefer(void);
  117.     void                setBusy(void);
  118.     void                setUnbusy(void);
  119.     void                autoBusy(void);
  120.     void                autoUnbusy(void);
  121.     static NeoCheckpoint
  122.                         GetCheckpoint(void);
  123.     static void            ResetCheckpoint(const NeoCheckpoint aCheckPoint);
  124.  
  125.                         /** Purge Methods **/
  126.     virtual Boolean        isPurgeable(NeoSize *aNeeded);
  127.     virtual Boolean        purge(NeoSize *aNeeded);
  128.  
  129. #ifdef qNeoDebug
  130.                         /** Debugging Methods **/
  131.     virtual const void *verify(const void *aValue) const;
  132. #endif
  133.  
  134.                         /** Instance Variables **/
  135. public:
  136.     NeoID                fID;                // Identity of the object
  137.     Boolean                fLeaf        : 1;    // not an inode?
  138.     Boolean                fRoot        : 1;    // node is the root of the tree?
  139.     Boolean                fTemporary    : 1;    // is a temporary object?
  140.     Boolean                fLocal        : 1;    // is locally visible only?
  141.     Boolean                fShareFill    : 2;    // Reserved for use by NeoShare
  142.     Boolean                fBusy        : 1;    // this node is being manipulated, don't change it!
  143.  
  144. protected:
  145.     Boolean                fBool1        : 1;    // spare boolean for use by subclasses of CNeoPersist
  146.  
  147.     Boolean                fBool2        : 1;    // spare boolean for use by subclasses of CNeoPersist
  148.     Boolean                fBool3        : 1;    // spare boolean for use by subclasses of CNeoPersist
  149.     Boolean                fReserved    : 2;    // Rest of byte reserved by NeoLogic for future use
  150. public:
  151.     NeoDirty            fPeerDirty    : 2;    // peer needs to be updated with state of this object?
  152.     NeoDirty            fDirty        : 2;    // Memory state different than file state
  153. protected:
  154.  
  155. public:
  156.     NeoVersion            fVersion;            // the object version number
  157.     NeoMark                fMark;                // Location of object in database
  158.     CNeoPersist *        fParent;            // Back pointer to this class's containing
  159.     NeoRefCnt            fRefCnt;            // Purgeable when zero
  160.  
  161.     static long            FCacheSize;            // Maximum size of the object cache
  162.     static long            FCacheUsed;            // Amount of space in cache being used
  163.     static long            FPurgeStart;        // Amount of space in cache as purge begins
  164.     static short        FPurgeDesperation;    // How desperate are we to find free memory?
  165.     static void *        FReserve;            // Pointer to a rainy-day memory reserve
  166.     static NeoReferTable *
  167.                         FReferTable;
  168.     static unsigned short
  169.                         FReferTableIndex;
  170.     static NeoBusyTable *
  171.                         FBusyTable;
  172.     static unsigned short
  173.                         FBusyTableIndex;
  174. };
  175.  
  176. const NeoTag pNeoFlags        =  Neo4CharConst('NP', 'fl');
  177. const NeoTag pNeoTemporary    =  Neo4CharConst('NP', 'tm');
  178. const NeoTag pNeoLocal        =  Neo4CharConst('NP', 'lo');
  179. const NeoTag pNeoBusy        =  Neo4CharConst('NP', 'bz');
  180. const NeoTag pNeoDirty        =  Neo4CharConst('NP', 'dy');
  181. const NeoTag pNeoRefCnt        =  Neo4CharConst('NP', 'rc');
  182.  
  183. #include <AEObjects.h>
  184. enum {kNeoPersistFileLength        = 2 + sizeof(NeoVersion)};
  185. #endif
  186.